This note clarifies MessageByName and provides examples of creating and retrieving a named message.
All you have to do is ask. Apple IIgs Toolbox Reference, Volume 3 already tells you how. Here's what the fine print says: with the createItFlag set to FALSE and the name of the message you are after in the nameString, you call MessageByName. What's unclear in the manual is that if the message was found, no error is returned, the createFlag is returned as FALSE, and messageID contains the ID you can pass to MessageCenter to retrieve the contents of the message. Here's an example of MessageByName in use.
The following code creates a named message.
CreateNamedMessage
pha
pha
pea 1 ;create it
pushlong #MsgBlock
_MessageByName ;function $1701
pla
sta myMsgID ;keep the ID if you want
pla ;check the createFlag if
; you want
...
MsgBlock dc.w MsgBlockEnd-MsgBlock
dc.b 28,'XYZ Software:My Cool Product' ;Pascal-style string
... more data goes here
MsgBlockEnd
The following code retrieves the message.
pha
pha
pea 0 ;don't create message
pushlong #MsgBlock
_MessageByName ;function $1701
ply ;keep id of existing
; message
pla ;createFlag (ignore)
bcs noMessage ;carry set if an error
; occurred
pea 2 ;MessageCenter action:GET
phy ;message ID for
; MessageCenter, below
pha
pha ;space for NewHandle
; result
lda #0 ;size of handle (0)
pha
pha
ldx MyID ;ID for empty
phx
pha ;handle attributes (0)
pha
pha ;no special location
_NewHandle
lda 3,s
sta mcHandle+2
lda 1,s
sta mcHandle ;keep a copy of the
; handle for later
_MessageCenter ;takes Action, Msg ID,
; and Handle
lda mcHandle+2
pha
lda mcHandle
pha
phd
tsc
tcd
ldy #2
lda [3],y
tax
lda [3]
sta 3
stx 5
* now read data from the message at [3]
ldy #$xxxx ;index past the name
; string
lda [3],y
...
pld
pla
pla
lda mcHandle+2
pha
lda mcHandle
pha
_DisposeHandle
noMessage ...
mcHandle dc.l 0
myMsgID dc.w 0
MessageByName is available in Tool Locator versions 3.0 and later (System Software 5.0 and later).
This and all of the other Apple II Technical Notes have been converted to HTML by Aaron Heiss as a public service to the Apple II community, with permission by Apple Computer, Inc. Any and all trademarks, registered and otherwise, are properties of their owners.